High level APIs

Besides the core functions and classes provided by the birdeec module, Birdee provides high level APIs that are written in Python based on the core APIs, to make it easier to do meta-programming using the scripts. The module names include bdconst, bdassert, bdutils, and traits. You can import the module in your scripts.

bdutils

This module provides some most handy functions that you may frequently need in your scripts. The functions falls into the following categroies.

AST creation and insertion

The make_* functions in this section create an AST node for the given type. The set_* functions create the AST and call the birdeec.set_ast function to insert the created AST to the current script AST.

def make_int(n: int)-> StatementASTUniquePtr : ...
def set_int(n: int): ...

def make_uint(n: int)-> StatementASTUniquePtr : ...
def set_uint(n: int): ...

def make_long(n: int)-> StatementASTUniquePtr : ...
def set_long(n: int): ...

def make_ulong(n: int)-> StatementASTUniquePtr : ...
def set_ulong(n: int): ...

# c should be a string of length 1. This function
# sets the script AST to the ASCII code of the character
def set_char(c: str)-> StatementASTUniquePtr : ...

def make_float(n: float)-> StatementASTUniquePtr : ...
def set_float(n: float): ...

def make_double(n: float)-> StatementASTUniquePtr : ...
def set_double(n: float): ...

def make_bool(n: bool)-> StatementASTUniquePtr : ...
def set_bool(n: bool): ...

def make_str(s: str)-> StatementASTUniquePtr : ...
def set_str(s: str): ...

def set_expr(s: str): ...
def set_stmt(s: str): ...

# resolve and set a type
def resolve_set_type(s: str): ...

Utilities for templates

These functions are utilities for getting information from the templates or functions.

#Get the template argument of the current class at a specific index
def get_cls_templ_at(idx)->TemplateArgument: ...
#Get the template argument of the current class at a specific index, and makes sure it is a type
def get_cls_type_templ_at(idx)-> ResolvedType: ...
#Get the template argument of the current class at a specific index, and makes sure it is an expression
def get_cls_expr_templ_at(idx)-> ExprASTUniquePtr: ...
#Get and set the template argument of the current class at a specific index as a type
def cls_templ_type_at(idx): ...
#Get and set the template argument of the current class at a specific index as a expression
def cls_templ_expr_at(idx): ...

#Get the definition of a parameter of a function
def get_func_arg_at(func: FunctionAST,idx)->VariableSingleDefAST: ...
#Get the template argument at a specific index of a function (by default the current function) 
def get_func_templ_at(idx, thefunc = None)->->TemplateArgument: ...
#Get the template argument as a type of the a function at a specific index (by default from the current function) 
def get_func_type_templ_at(idx, thefunc = None)-> ResolvedType: ...
#Get the template argument as an expression of the a function at a specific index (by default from the current function) 
def get_func_expr_templ_at(idx, thefunc = None)-> ExprASTUniquePtr: ...
#Get and set the template argument of a function at a specific index as a type (by default from the current function)
def func_templ_type_at(idx, thefunc = None):...
#Get and set the template argument of a function at a specific index as a type (by default from the current function)
def func_templ_expr_at(idx, thefunc = None):...

bdconst

This module enables developers to generate constant integers in Birdee code.

def define(name, value):...

The define function takes two parameters, name is the name of the defined constant. value is the integer value of the constant. After you call this function, two Python variables are defined in the Python globals, which have the names name and _name ("name" has been specified by the parameter). The name variable is a function that will generate an constant integer AST node and set the current AST using the generated AST. The _name variable is a Python integer that has the same value of value parameter of the define function. Here we give an example of using define function:

{@
from bdconst import define
define("CONST1", 1)
define("CONST2", 2)
print(_CONST1)
print(_CONST2)
@}

dim v1 = {@CONST1()@}
dim v2 = {@CONST2()@}

After compiling the above example, the compiler will print the values of _CONST1 and _CONST2 which are 1 and 2. The Birdee variables v1 and v2 have the initial values of 1 and 2.

bdassert

This module provides the code generator that can do runtime assertion. In Birdee programs, developers may have some assertions on the states of the program. The condition of the assertion will be checked at the run time. If the condition does not hold, a runtime_exception will be raised.

def bdassert(expr: str):...

The bdassert function takes one parameter that is the Birdee source code string for the condition to check. This function will generate the input source code as an expression and also generate the code to check if the generated expression is true. The expr should be a boolean Birdee expression. Here is an example:

{@from bdassert import *@}
function complicated() as int
    ...
end

dim v as int = compilcated()
{@bdassert("v!=0")@}
println(int2str(32/v))

The above example uses bdassert to make sure that v is never 0. If it is zero, an exception will be throw. The bdassert function is useful for debugging and testing.